<HTML>
<HEAD>
<TITLE> CSPICE Required Reading </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>CSPICE Required Reading</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#CSPICE Required Reading">CSPICE Required Reading</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#Design Concept">Design Concept</A>
         <A HREF="#Programming Standards">Programming Standards</A>
         <A HREF="#Testing">Testing</A>
         <A HREF="#CSPICE functionality">CSPICE functionality</A>
      <A HREF="#The CSPICE API">The CSPICE API</A>
      <A HREF="#Documentation">Documentation</A>
      <A HREF="#Kernel files">Kernel files</A>
      <A HREF="#Installation">Installation</A>
         <A HREF="#Directory Structure">Directory Structure</A>
         <A HREF="#Platforms">Platforms</A>
      <A HREF="#Calling CSPICE Wrappers">Calling CSPICE Wrappers</A>
         <A HREF="#Linking against CSPICE">Linking against CSPICE</A>
         <A HREF="#CSPICE data types">CSPICE data types</A>
         <A HREF="#Interface macros">Interface macros</A>
         <A HREF="#CSPICE public declarations">CSPICE public declarations</A>
         <A HREF="#CSPICE function prototypes">CSPICE function prototypes</A>
      <A HREF="#Calling functions generated by f2c">Calling functions generated by f2c</A>
         <A HREF="#f2c's specification">f2c's specification</A>
         <A HREF="#Header files">Header files</A>
         <A HREF="#f2c data types">f2c data types</A>
         <A HREF="#Call by reference">Call by reference</A>
         <A HREF="#Arrays">Arrays</A>
         <A HREF="#Strings">Strings</A>
         <A HREF="#Arrays of strings">Arrays of strings</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="CSPICE Required Reading"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> CSPICE Required Reading
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2006 NOV 20 by B. V. Semenov.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE is an ANSI C version of the SPICE Toolkit. CSPICE provides
   essentially the same functionality as the Fortran SPICE Toolkit, with
   very slight differences where necessitated by differences in the
   capabilities of standard ANSI C as opposed to Fortran.
<P>
 
<BR><BR>
<A NAME="Design Concept"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Design Concept
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Like the Fortran SPICE Toolkit, CSPICE contains library routines,
   executable programs, documentation, and example ``cookbook'' programs.
   Source code is provided for both libraries and executables.
<P>
 
   NAIF creates the basis for CSPICE by running the Fortran-to-C
   translation utility, f2c, on the Fortran SPICELIB code base.
<P>
 
<BR><BR>
<A NAME="Programming Standards"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Programming Standards
</H3><P><BR><BR>
   NAIF intends CSPICE source code to comply with the ANSI C standard and
   meant to be compiled under ANSI compliant C compilers; the code relies
   on features supplied in ANSI C not present in the original Kernighan and
   Ritchie version of C.
<P>
 
   All CSPICE source code written by NAIF uses ANSI C. C source code
   produced by running f2c on SPICELIB Fortran source code has been
   generated using the f2c processor's "ANSI" option (-A). The degree of
   deviation of this code from the ANSI standard, if any, is not currently
   known. The degree of ANSI compliance of the source code in the f2c I77
   and F77 libraries is also unknown.
<P>
 
<BR><BR>
<A NAME="Testing"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Testing
</H3><P><BR><BR>
   NAIF subjects CSPICE to an extensive set of tests designed to exercise
   the f2c's and wrapper code. These tests run on all supported platforms.
<P>
 
<BR><BR>
<A NAME="CSPICE functionality"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> CSPICE functionality
</H3><P><BR><BR>
<UL>
<TT>--</TT> SPK: loader, readers, writers
<BR><BR></UL>
<UL>
<TT>--</TT> Binary PCK: loader, readers
<BR><BR></UL>
<UL>
<TT>--</TT> CK: loader, readers, writers
<BR><BR></UL>
<UL>
<TT>--</TT> EK: loader, query and fetch functions, fast writers, record-oriented write,
update, and read functions, summary functions
<BR><BR></UL>
<UL>
<TT>--</TT> DAF: array search and summary functions
<BR><BR></UL>
<UL>
<TT>--</TT> Kernel pool: loader, summary, fetch, watcher, kernel pool write access
routines
<BR><BR></UL>
<UL>
<TT>--</TT> Coordinate systems: translation between rectangular and cylindrical,
latitudinal, geodetic, and RA/Dec systems.
<BR><BR></UL>
<UL>
<TT>--</TT> Body name/code translation
<BR><BR></UL>
<UL>
<TT>--</TT> Matrix and vector functions
<BR><BR></UL>
<UL>
<TT>--</TT> Rotation functions
<BR><BR></UL>
<UL>
<TT>--</TT> Euler angle functions
<BR><BR></UL>
<UL>
<TT>--</TT> Quaternion functions
<BR><BR></UL>
<UL>
<TT>--</TT> Time conversion functions
<BR><BR></UL>
<UL>
<TT>--</TT> Spacecraft clock functions
<BR><BR></UL>
<UL>
<TT>--</TT> Ellipsoid functions: near point, surface intercept, outward normal
<BR><BR></UL>
<UL>
<TT>--</TT> SPICE ellipse and plane functions
<BR><BR></UL>
<UL>
<TT>--</TT> SPICE error handling functions
<BR><BR></UL>
<UL>
<TT>--</TT> Higher level geometry functions: sub-observer point, sub-solar point,
illumination angles
<BR><BR></UL>
<UL>
<TT>--</TT> Constant functions: standard epochs, radian/degree conversion, speed of
light
<BR><BR></UL>
<UL>
<TT>--</TT> Array manipulation functions
<BR><BR></UL>
<UL>
<TT>--</TT> Frame utilities: map body to associated frame, get descriptive information
for a specified frame
<BR><BR></UL>
<UL>
<TT>--</TT> File utilities: map kernel to architecture and type, close file opened by
translated Fortran code, test whether file exists
<BR><BR></UL>
<UL>
<TT>--</TT> String utilities: case-insensitive string equivalence, white space
equivalence, last non-blank, case conversion.
<BR><BR></UL>
<UL>
<TT>--</TT> Numeric utilities: maximum and minimum integers and double precision
numbers, maximum and minimum of sets of scalars
<BR><BR></UL>
<UL>
<TT>--</TT> Windows, Set, and Cell functions
<BR><BR></UL>
   CSPICE contains counterparts of the Fortran SPICE Toolkit's executables:
<P>
 
<UL>
<TT>--</TT> Brief - A command line utility used to summarize the information within an
SPK file.
<BR><BR></UL>
<UL>
<TT>--</TT> Chronos - A utility used to convert time values between various formats,
e.g. UTC to ET, Et to SCLK, etc.
<BR><BR></UL>
<UL>
<TT>--</TT> CKbrief - A command line utility used to summarize the pointing data within
a CK file.
<BR><BR></UL>
<UL>
<TT>--</TT> Commnt - A utility, usable in either interactive or command line mode, used
to examine and manipulate the comment area of a SPICE binary kernel.
<BR><BR></UL>
<UL>
<TT>--</TT> Inspekt - An interactive program used to examine and query to contents of
an E-kernel.
<BR><BR></UL>
<UL>
<TT>--</TT> MkSPK - An application used to create, or append to, SPK files.
<BR><BR></UL>
<UL>
<TT>--</TT> Spacit - An interactive application used to manipulate and examine SPK
files.
<BR><BR></UL>
<UL>
<TT>--</TT> SPKmerge - An application used to merge several SPK files or subsets of SPK
files into a single SPK file.
<BR><BR></UL>
<UL>
<TT>--</TT> Tobin - A command line utility used to convert SPICE ASCII transfer files
to architecture native binary kernels.
<BR><BR></UL>
<UL>
<TT>--</TT> Toxfr - A command line utility used to convert SPICE binary kernels to
ASCII transfer format.
<BR><BR></UL>
<UL>
<TT>--</TT> Version - A command line utility that outputs the SPICE toolkit version and
platform specific parameters: System, OS, Compiler, binary file type
(big/little endian IEEE, non-IEEE, etc.), line terminator, values for
min/max DPs, and values for min/max INTs.
<BR><BR></UL>
   The CSPICE versions of these executables function identically to that of
   the Fortran versions. The sole difference is cosmetic: in some cases,
   the appearance of white space in these programs' output differs slightly
   from that produced by the corresponding Fortran SPICE Toolkit
   implementations.
<P>
 
   CSPICE contains the following cookbook programs:
<P>
 
<UL>
<TT>--</TT> SIMPLE: this program calculates the angular separation of two target bodies
as seen from a specified observer.
<BR><BR></UL>
<UL>
<TT>--</TT> STATES: this program calculates the state (position and velocity) of a
target body relative to an observer, at a specified epoch. Observer and
target are specified by the user.
<BR><BR></UL>
<UL>
<TT>--</TT> SUBPT: this program calculates the planetocentric latitude and longitude of
the nearest point on a target body to an observer. The target, observer,
and epoch are user-specified.
<BR><BR></UL>
<UL>
<TT>--</TT> TICTOC: this program performs conversion between UTC and ET.
<BR><BR></UL>
   Cookbook programs are intended to provide a simple, concrete
   introduction to programming with CSPICE. If you are a new CSPICE user,
   NAIF recommends that you examine the source code of the cookbook
   programs and that you also try building and running them.
<P>
 
<BR><BR>
<A NAME="The CSPICE API"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The CSPICE API
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The CSPICE API is designed to mimic the corresponding Fortran interface,
   while adhering to natural C-language argument list conventions. The
   following conventions are followed:
<P>
 
<UL>
<TT>--</TT> String arguments are C-style: strings are always null-terminated on input
and output.
<BR><BR></UL>
<UL>
<TT>--</TT> Each output string argument has a corresponding input length argument via
which the caller indicates how much room is available in the output string.
<BR><BR></UL>
<UL>
<TT>--</TT> Multi-dimensional arrays have normal C-style storage order: the rightmost
index varies the fastest. For 2-dimensional matrices, this means the matrix
storage is in row-major order. This is the transpose of the Fortran order.
<BR><BR></UL>
<UL>
<TT>--</TT> Arguments involving arrays of strings are implemented as two-dimensional
character arrays, not arrays of character pointers.
<BR><BR></UL>
<UL>
<TT>--</TT> CSPICE typedefs (discussed below) are used to declare all arguments and
function return values.
<BR><BR></UL>
   Functions not belonging to the API DO NOT FOLLOW the above conventions.
<P>
 
   Each API function contains a complete NAIF-style header documenting the
   specification of that function. These hand-coded API functions are
   called ``wrappers.'' They typically serve to encapsulate C code
   generated by f2c. However, many of the simpler routines, such as the
   linear algebra functions, are fully coded anew in C and do not call
   translated Fortran routines.
<P>
 
   Wrapper calls are denoted by file names ending with the suffix
<P>
 
<PRE>
   _c
</PRE>
   Wrapper source files have file names ending in
<P>
 
<PRE>
   _c.c
</PRE>
   Functions created by f2c have names ending with the suffix
<P>
 
<PRE>
   _
</PRE>
   (underscore). The underscore does not appear in the corresponding source
   file names.
<P>
 
   The few routines written in C that replace modules generated by f2c
   follow the same function and source file naming conventions as the code
   generated by f2c.
<P>
 
   Users' application functions calling the CSPICE API must include the
   CSPICE header file SpiceUsr.h. This header file defines function
   prototypes for each CSPICE API routine. Also, typedefs used in the
   prototypes are declared by this header.
<P>
 
   Below is a code fragment showing inclusion of SpiceUsr.h and a call to
   the SPK reader function <a href="../cspice/spkezr_c.html">spkezr_c</a>.
<P>
 
<PRE>
   #include "SpiceUsr.h"
 
   SpiceDouble    et;
   SpiceDouble    lt;
   SpiceDouble    state [6];
             .
             .
             .
   <a href="../cspice/spkezr_c.html">spkezr_c</a> ( "SUN", et, "J2000", "LT+S", "EARTH", state, &amp;lt );
</PRE>
<BR><BR>
<A NAME="Documentation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Documentation
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The CSPICE documentation set consists of:
<P>
 
<UL>
<TT>--</TT> Reference Guide. A set of HTML pages consisting of the header information
from each wrapper file. The pages include cross-links to other reference
pages when a header references any wrapper, i.e. if a page refers to
another wrapper, a link exists to that wrapper's HTML page.
<BR><BR></UL>
<UL>
<TT>--</TT> Required Reading files. These are C-oriented versions of the corresponding
documents in the Fortran SPICE Toolkit. CSPICE provides C versions of the
following Required Reading files:
<BR><BR></UL>
<PRE>
            <a href="../req/cells.html">cells.req</a>
            <a href="../req/ck.html">ck.req</a>
            <a href="../req/ek.html">ek.req</a>
            <a href="../req/error.html">error.req</a>
            <a href="../req/frames.html">frames.req</a>
            <a href="../req/kernel.html">kernel.req</a>
            <a href="../req/naif_ids.html">naif_ids.req</a>
            <a href="../req/pck.html">pck.req</a>
            <a href="../req/problems.html">problems.req</a>
            <a href="../req/rotation.html">rotation.req</a>
            <a href="../req/sclk.html">sclk.req</a>
            <a href="../req/sets.html">sets.req</a>
            <a href="../req/spc.html">spc.req</a>
            <a href="../req/spk.html">spk.req</a>
            <a href="../req/time.html">time.req</a>
            <a href="../req/windows.html">windows.req</a>
</PRE>
<UL>
<TT>&#32;&#32;</TT> Several Fortran Required Reading files have not yet been converted to C
style; the Fortran versions of these are included in CSPICE. These files
are:
<BR><BR></UL>
<PRE>
            <a href="../req/daf.html">daf.req</a>
            <a href="../req/das.html">das.req</a>
            <a href="../req/ellipses.html">ellipses.req</a>
            <a href="../req/planes.html">planes.req</a>
            <a href="../req/scanning.html">scanning.req</a>
            <a href="../req/symbols.html">symbols.req</a>
</PRE>
<UL>
<TT>--</TT> User's Guides. These are the same documents provided in the Fortran SPICE
Toolkit.
<BR><BR></UL>
<PRE>
            <a href="../ug/brief.html">brief.ug</a>
            <a href="../ug/chronos.html">chronos.ug</a>
            <a href="../ug/ckbrief.html">ckbrief.ug</a>
            <a href="../ug/commnt.html">commnt.ug</a>
            <a href="../ug/convert.html">convert.ug</a>
            <a href="../ug/inspekt.html">inspekt.ug</a>
            <a href="../ug/mkspk.html">mkspk.ug</a>
            <a href="../ug/msopck.html">msopck.ug</a>
            <a href="../ug/simple.html">simple.ug</a>
            <a href="../ug/spacit.html">spacit.ug</a>
            <a href="../ug/spkdiff.html">spkdiff.ug</a>
            <a href="../ug/spkmerge.html">spkmerge.ug</a>
            <a href="../ug/states.html">states.ug</a>
            <a href="../ug/subpt.html">subpt.ug</a>
            <a href="../ug/tictoc.html">tictoc.ug</a>
            <a href="../ug/tobin.html">tobin.ug</a>
            <a href="../ug/toxfr.html">toxfr.ug</a>
            <a href="../ug/version.html">version.ug</a>
</PRE>
<UL>
<TT>--</TT> A permuted index, cspice.idx. This document maps brief abstracts describing
functionality of routines to names of routines.
<BR><BR></UL>
   The documentation includes the User's Guides and Required Readings in
   text and HTML format. The index.html file in the icy/doc/html
   subdirectory is the CSPICE HTML documentation "homepage."
<P>
 
<BR><BR>
<A NAME="Kernel files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Kernel files
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   For each platform, CSPICE uses the same binary and text kernels as the
   Fortran SPICE Toolkit for that platform.
<P>
 
   As of release N0059, the kernel pool readers (<a href="../cspice/ldpool_c.html">ldpool_c</a>, <a href="../cspice/furnsh_c.html">furnsh_c</a>) have
   the capability to read non platform-native text kernels, e.g. read a DOS
   native text file on a Unix platform and vice-versa. This capability does
   not exist in the Fortran toolkit.
<P>
 
   Transfer format files produced by the CSPICE versions of SPACIT and
   TOXFR have very slight white space differences as compared with transfer
   format files produced by the Fortran counterparts of these programs.
   These differences do not affect the functioning of the transfer files:
   those produced by the Fortran SPICE Toolkit may be used with CSPICE and
   vice versa.
<P>
 
<BR><BR>
<A NAME="Installation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Installation
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE is obtained and installed in a manner completely analogous to
   that used for the Fortran SPICE Toolkit. Access the NAIF site for
   download instructions at URL:
<P>
 
<PRE>
      http://naif.jpl.nasa.gov/naif/toolkit.html
</PRE>
<BR><BR>
<A NAME="Directory Structure"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Directory Structure
</H3><P><BR><BR>
   The package has the same directory structure as SPICELIB, with the
   addition of an html subdirectory of the doc directory:
<P>
 
<PRE>
                                 cspice
                                    |
                                    |
   /data   /doc   /etc   /exe   /include   /lib   /src   makeall
             |                               |      |
             |                               |      |
             |                               |      |
         /html  *.req ...                    |  /cspice /cook_c ...
             |                               |
         index.html                          |
                                             |
                                    cspice.a  csupport.a
</PRE>
   with 'makeall' a master build script specific to the platform
   architecture.
<P>
 
<BR><BR>
<A NAME="Platforms"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Platforms
</H3><P><BR><BR>
   CSPICE currently is supported on the following platforms:
<P>
 
<PRE>
   Hardware      Operating system    Compiler
   --------      ----------------    --------
   PC            Linux               gcc
   PC            MS Windows          MS Visual Studio C++/C .Net
   Sun Sparc     Solaris 32 bit      Sun C
   Sun Sparc     Solaris 64 bit      Sun C
   Sun Sparc     Solaris 32 bit      gcc
   Macintosh     OS X                cc (gcc)
</PRE>
<BR><BR>
<A NAME="Calling CSPICE Wrappers"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Calling CSPICE Wrappers
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   As indicated above, functions calling the CSPICE API must include the
   header file SpiceUsr.h. The code in this header file makes use of ANSI C
   features, so functions including it must be compiled as ANSI C. No
   special precompiler flags are needed to compile SpiceUsr.h.
<P>
 
   On a Unix system, a typical compiler invocation for a function that
   calls CSPICE would look like:
<P>
 
<PRE>
   cc -c &lt;ANSI flag&gt; userfunc.c
</PRE>
   This presumes that SpiceUsr.h is present in the current working
   directory. Under some compilers, the option
<P>
 
<PRE>
   -I&lt;path&gt;
</PRE>
   may be used to designate a path to search for include files.
<P>
 
   Examples of ANSI flags are:
<P>
 
<PRE>
   Sun C compiler              -Xc
   gcc                         -ansi
</PRE>
   So, on a Sun/Solaris system, with CSPICE installed in the path
<P>
 
<PRE>
   /home/cspice
</PRE>
   a function userfunc.c that calls CSPICE could be compiled using the
   command
<P>
 
<PRE>
   cc -c -Xc -I/home/cspice/src/cspice userfunc.c
</PRE>
   Under Microsoft Visual C/C++, the compiler invocation requires no
   special flag to indicate usage of ANSI C. On this platform, you may find
   it necessary to set the INCLUDE, LIB, and PATH environment variables in
   order to use the command line compiler and linker, as shown below.
<P>
 
<PRE>
   Set DOS Environment variables (XP) for Visual Studio 7:
 
   To set:
      Control Panel -&gt; System
                       select "Advanced" tab
                       push "Environment Variables" button
                       chose variable name
                       push "Edit" button
                       paste-in or type path strings
 
   INCLUDE
   C:\Program Files\Microsoft Visual Studio .NET\Vc7\include\;
   C:\Program Files\Microsoft Visual Studio .NETFrameworkSDK\include\
 
   LIB
   C:\Program Files\Microsoft Visual Studio .NET\Vc7\lib\;
   C:\Program Files\Microsoft Visual Studio .NETFrameworkSDK\Lib\
 
   PATH
   C:\Program Files\Microsoft Visual Studio .Net\Vc7\bin
</PRE>
<BR><BR>
<A NAME="Linking against CSPICE"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Linking against CSPICE
</H3><P><BR><BR>
   On Unix systems, programs linking against CSPICE must also link against
   the C math library; this is normally accomplished using the ``-lm'' flag
   following cspice.a in the link command. A typical link command might
   look like
<P>
 
<PRE>
   cc -o myprog myprog.o &lt;user objects&gt; &lt;user libs&gt; \
   &lt;lib path&gt;/cspice.a -lm
</PRE>
   Under Microsoft Visual C/C++, no reference to the C math library is
   required. On this platform, a typical link command would look like:
<P>
 
<PRE>
   cl myprog.obj &lt;user objects&gt; &lt;user libs&gt; &lt;lib path&gt;\cspice.lib
</PRE>
   It is not necessary to reference the CSUPPORT library in link
   statements: CSPICE does not reference it. CSUPPORT is required only to
   build the CSPICE utility programs.
<P>
 
<BR><BR>
<A NAME="CSPICE data types"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> CSPICE data types
</H3><P><BR><BR>
   To assist with long-term maintainability, CSPICE uses typedefs to
   represent data types occurring in argument lists and as return values of
   CSPICE functions. The CSPICE typedefs for fundamental types are:
<P>
 
<PRE>
   SpiceBoolean
   SpiceChar
   SpiceDouble
   SpiceInt
   ConstSpiceBoolean
   ConstSpiceChar
   ConstSpiceDouble
   ConstSpiceInt
</PRE>
   The SPICE typedefs map in an arguably natural way to ANSI C types:
<P>
 
<PRE>
   SpiceBoolean -&gt; int
   SpiceChar    -&gt; char
   SpiceDouble  -&gt; double
   SpiceInt     -&gt; int or long
   ConstX       -&gt; const X  (X = any of the above types)
</PRE>
   The type SpiceInt is a special case: the corresponding type is picked so
   as to be half the size of a double. On all currently supported
   platforms, type double occupies 8 bytes and type int occupies 4 bytes.
   Other platforms may require a SpiceInt to map to type long.
<P>
 
   Ellipses and planes are represented by structures; these and their
   const-qualified counterparts are:
<P>
 
<PRE>
   SpiceEllipse
   ConstSpiceEllipse
   SpicePlane
   ConstSpicePlane
</PRE>
   A small number of more specialized types have been introduced to support
   the EK query interface. These are:
<P>
 
<PRE>
   SpiceEKAttDsc      {EK column attribute descriptor}
   SpiceEKSegSum      {EK segment summary}
   SpiceEKDataType    {Column data types}
   SpiceEKExprClass   {SELECT clause expression class}
</PRE>
   These are described in the header SpiceEK.h.
<P>
 
   While other data types may be used internally in CSPICE, no other types
   appear in the API.
<P>
 
<BR><BR>
<A NAME="Interface macros"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Interface macros
</H3><P><BR><BR>
   To better support calling the CSPICE API from within C++, as well as to
   provide better compile-time error checking, CSPICE prototypes declare
   input-only array or pointer arguments using const qualification.
<P>
 
   For example, here is the function prototype for <a href="../cspice/mxm_c.html">mxm_c</a>, CSPICE's 3 by 3
   matrix multiplication function:
<P>
 
<PRE>
   void              <a href="../cspice/mxm_c.html">mxm_c</a>    ( ConstSpiceDouble    m1  [3][3],
                                ConstSpiceDouble    m2  [3][3],
                                SpiceDouble         mout[3][3] );
</PRE>
   It turns out that various popular compilers issue compilation warnings
   when non-const-qualified actual arguments are supplied to functions
   whose prototypes call for const inputs.
<P>
 
   For example, the code fragment:
<P>
 
<PRE>
   double m1   [3][3];
   double m2   [3][3];
   double mout [3][3];
       .
       .
       .
   <a href="../cspice/mxm_c.html">mxm_c</a> ( m1, m2, mout );
</PRE>
   would generate compilation warnings on some systems: the diagnostics
   would complain that m1 and m2 are not const, even though there's no
   particular risk of error introduced by passing these arrays to a routine
   expecting const inputs.
<P>
 
   Explicitly adding type casts to satisfy the compiler is possible but
   awkward: the call to <a href="../cspice/mxm_c.html">mxm_c</a> would then look like:
<P>
 
<PRE>
   <a href="../cspice/mxm_c.html">mxm_c</a> ( (const double (*)[3])m1,
           (const double (*)[3])m2, mout);
</PRE>
   Instead, to suppress these spurious diagnostics, CSPICE supplies
   interface macros which automatically provide the desired type casts.
   These macros have the same names and argument counts as the wrapper
   functions which they call.
<P>
 
   The interface macros have been designed to be transparent to users; they
   do not differ from their underlying wrappers in the way arguments are
   evaluated; in particular they do not have any unusual side effects.
<P>
 
   As an example, here is the interface macro for <a href="../cspice/mxm_c.html">mxm_c</a>:
<P>
 
<PRE>
   #define  <a href="../cspice/mxm_c.html">mxm_c</a>( m1, m2, mout )                             \
                                                              \
        (   <a href="../cspice/mxm_c.html">mxm_c</a> ( CONST_MAT(m1), CONST_MAT(m2), (mout) )   )
</PRE>
   The macro CONST_MAT is defined as
<P>
 
<PRE>
   #define  CONST_MAT          ( ConstSpiceDouble   (*) [3] )
</PRE>
   With this macro defined, the call
<P>
 
<PRE>
   <a href="../cspice/mxm_c.html">mxm_c</a> ( m1, m2, mout );
</PRE>
   actually invokes the <a href="../cspice/mxm_c.html">mxm_c</a> interface macro, which in turn generates a
   call to the function <a href="../cspice/mxm_c.html">mxm_c</a> with const-qualified inputs.
<P>
 
   The definitions of the interface macros are automatically included when
   a calling program includes the CSPICE header file SpiceUsr.h.
<P>
 
<BR><BR>
<A NAME="CSPICE public declarations"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> CSPICE public declarations
</H3><P><BR><BR>
   In addition to the interface macros discussed above, CSPICE declares a
   small set of public macros.
<P>
 
   Boolean values:
<P>
 
<PRE>
   SPICEFALSE
   SPICETRUE
</PRE>
   Status codes:
<P>
 
<PRE>
   SPICEFAILURE
   SPICESUCCESS
</PRE>
   EK public constants:
<P>
 
<PRE>
   SPICE_EK_*
</PRE>
   There are no definitions of variables or functions introduced by the
   public header file SpiceUsr.h.
<P>
 
<BR><BR>
<A NAME="CSPICE function prototypes"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> CSPICE function prototypes
</H3><P><BR><BR>
   Because CSPICE function prototypes enable substantial compile-time error
   checking, we recommend that user applications always reference them.
   Include the header file SpiceUsr.h in any module that calls CSPICE to
   make the prototypes available.
<P>
 
<BR><BR>
<A NAME="Calling functions generated by f2c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Calling functions generated by f2c
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="f2c's specification"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> f2c's specification
</H3><P><BR><BR>
   The specification of the automatic Fortran-to-C translation program f2c
   can be summarized thusly: f2c attempts to create C code whose
   functionality is identical to that of the source Fortran code. Due to
   limitations of C and the system-dependent behavior of Fortran I/O, f2c
   cannot always completely succeed in fulfilling its nominal
   specification. However, the function argument lists generated by f2c can
   be understood by remembering that they act very much like Fortran,
   rather than C, argument lists.
<P>
 
   f2c's treatment of argument data types occurring in the Fortran library
   SPICELIB are discussed below.
<P>
 
<BR><BR>
<A NAME="Header files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Header files
</H3><P><BR><BR>
   Prototypes and associated declarations for functions generated by f2c
   are provided in the header file SpiceZfc.h. This header must be included
   by any application code that calls these translated functions. The
   typical sequence of header inclusions is:
<P>
 
<PRE>
   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
</PRE>
<BR><BR>
<A NAME="f2c data types"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> f2c data types
</H3><P><BR><BR>
   f2c uses typedefs to represent C data types used in the translated
   Fortran functions f2c creates. The Fortran data types used in the
   Fortran library SPICELIB and the corresponding typedefs generated by f2c
   are as follows:
<P>
 
<PRE>
   Fortran type                f2c typedef
   ------------                -----------
 
   DOUBLE PRECISION            doublereal
   INTEGER                     integer
   LOGICAL                     logical
   CHARACTER                   char
</PRE>
   In addition, there is a special typedef used for arguments used to
   represent string lengths:
<P>
 
<PRE>
   ftnlen
</PRE>
   See ``Strings'' below for more about string arguments.
<P>
 
<BR><BR>
<A NAME="Call by reference"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Call by reference
</H3><P><BR><BR>
   With one exception, all arguments of functions generated by f2c are
   pointers. Passing input arguments by value is not permitted. To supply a
   value as an input argument, the value must be placed in a variable, and
   the address of the variable passed as an actual argument.
<P>
 
   The one exception to the rule is string length arguments. These are
   always passed by value.
<P>
 
<BR><BR>
<A NAME="Arrays"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Arrays
</H3><P><BR><BR>
   The CSPICE wrappers handle the differences between C and Fortran
   concerning the ordering of array data in memory.
<P>
 
   In Fortran, the ordering in memory of array elements is such that the
   index corresponding to the leftmost dimension of the array varies the
   most rapidly. For example, for two-dimensional arrays, the first column
   is at the start of the memory occupied by the array, the second column
   comes next, and so on. This is called ``column major'' order, and is the
   transpose of the order used in C.
<P>
 
   Consequently, matrix arguments to functions generated by f2c must be
   transposed prior to input and after output in order to be correctly used
   by a calling C program. The CSPICE functions <a href="../cspice/xpose_c.html">xpose_c</a> and <a href="../cspice/xpose6_c.html">xpose6_c</a> may be
   used to transpose 3x3 and 6x6 matrices respectively.
<P>
 
<BR><BR>
<A NAME="Strings"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Strings
</H3><P><BR><BR>
   In Fortran, the ability to determine the declared length of a string is
   built into the language. Fortran strings are not null terminated; unused
   space in the trailing portion of a string is padded with blanks.
<P>
 
   Functions generated by f2c must be able to determine the length of
   strings on input without relying on null termination; on output, strings
   are returned from these functions blank-padded without null termination.
<P>
 
   When f2c processes a Fortran character string argument, the argument
   list of the output C function contains two arguments corresponding to
   the single Fortran string argument: a character pointer argument and a
   string length argument. The string length arguments occur consecutively
   at the end of the function's argument list. The nth string length
   argument gives the string length of the nth string argument.
<P>
 
   For example, the Fortran argument list:
<P>
 
<PRE>
   CHARACTER*(80)     TARG
   DOUBLE PRECISION   ET
   CHARACTER*(10)     REF
   CHARACTER*(4)      ABCORR
   CHARACTER*(80)     OBS
   DOUBLE PRECISION   STATE
   DOUBLE PRECISION   LT
 
   SPKEZR ( TARG, ET, REF, ABCORR, OBS, STATE, LT )
</PRE>
   translates to the C argument list:
<P>
 
<PRE>
   int spkezr_ (  char        * targ,
                  doublereal  * et,
                  char        * ref,
                  char        * abcorr,
                  char        * obs,
                  doublereal  * state,
                  doublereal  * lt,
                  ftnlen        target_namlen,
                  ftnlen        ref_namlen,
                  ftnlen        abcorr_namlen,
                  ftnlen        obs_namlen     )
</PRE>
   Note: An API wrapper function exists for spkezr_; the prototype for the
   wrapper function <a href="../cspice/spkezr_c.html">spkezr_c</a> is the simpler:
<P>
 
<PRE>
   void <a href="../cspice/spkezr_c.html">spkezr_c</a> ( ConstSpiceChar    * targ,
                   SpiceDouble         et,
                   ConstSpiceChar    * ref,
                   ConstSpiceChar    * abcorr,
                   ConstSpiceChar    * obs,
                   SpiceDouble         state[6],
                   SpiceDouble       * lt       )
</PRE>
   The string length arguments give counts of characters excluding
   terminating nulls. For input arguments, the strlen function can be used
   to compute string lengths.
<P>
 
   The character string arguments generated by f2c are expected to contain
   Fortran-style strings: a string argument should not contain a null
   terminator unless it is part of the string's data. Output strings will
   not be null-terminated but will be padded up to the designated length
   with trailing blanks.
<P>
 
<BR><BR>
<A NAME="Arrays of strings"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Arrays of strings
</H3><P><BR><BR>
   In f2c created functions, string array arguments are particularly tricky
   because of the difference in the way C and Fortran determine string
   lengths. A C array of N strings of declared length M maps to a Fortran
   array of N strings of length M-1, since the Fortran string array
   contains no null terminators. So, preparing a C string array to be
   passed as an input to a function generated by f2c requires creating a
   new array without null terminators. Similarly, an output string array
   from a function generated by f2c must have null terminators added.
<P>
 
   If you find it necessary to call one of these functions, we suggest you
   contact NAIF; we'll provide you with a C wrapper for the function in
   question.
<P>
 

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
